Scripting
Getting Started
Documentation
Changelog
Privacy
Getting Started
Documentation
Changelog
Privacy

Reading Correlation Data

The Scripting app allows you to query correlated health data using the global Health.queryCorrelations() API. A correlation groups related health samples into a single logical event — such as a blood pressure reading (systolic and diastolic) or a food intake record (calories, protein, etc.).

This guide explains how to retrieve and interpret correlation data from HealthKit.

What Is a Correlation?

A correlation in HealthKit represents a composite health event made up of multiple samples, including:

  • "bloodPressure" — combines bloodPressureSystolic and bloodPressureDiastolic
  • "food" — may include dietaryEnergyConsumed, dietaryProtein, dietaryCarbohydrates, etc.

Each correlation includes:

  • Start and end date
  • Type ("bloodPressure" or "food")
  • Metadata (optional)
  • Associated samples (quantity or category samples)

API Overview

1Health.queryCorrelations(
2  correlationType: HealthCorrelationType,
3  options?: {
4    startDate?: Date
5    endDate?: Date
6    limit?: number
7    strictStartDate?: boolean
8    strictEndDate?: boolean
9    sortDescriptors?: Array<{
10      key: "startDate" | "endDate"
11      order?: "forward" | "reverse"
12    }>
13  }
14): Promise<HealthCorrelation[]>

Parameters

Parameter Description
correlationType "bloodPressure" or "food"
startDate/endDate Query time range
limit Maximum number of correlations to return
strictStartDate/strictEndDate Whether to match exact boundaries
sortDescriptors Sort by startDate or endDate (optional)

Example: Query Blood Pressure Correlations

1const correlations = await Health.queryCorrelations("bloodPressure", {
2  startDate: new Date("2025-07-01T00:00:00"),
3  endDate: new Date("2025-07-02T00:00:00"),
4  limit: 5,
5  sortDescriptors: [{ key: "startDate", order: "reverse" }]
6})
7
8for (const correlation of correlations) {
9  console.log("Start:", correlation.startDate)
10  console.log("End:", correlation.endDate)
11
12  const systolic = correlation.quantitySamples.find(
13    s => s.quantityType === "bloodPressureSystolic"
14  )
15
16  const diastolic = correlation.quantitySamples.find(
17    s => s.quantityType === "bloodPressureDiastolic"
18  )
19
20  if (systolic && diastolic) {
21    const sys = systolic.quantityValue(HealthUnit.millimeterOfMercury())
22    const dia = diastolic.quantityValue(HealthUnit.millimeterOfMercury())
23    console.log(`Blood Pressure: ${sys}/${dia} mmHg`)
24  }
25}

Example: Query Food Correlations

1const correlations = await Health.queryCorrelations("food", {
2  startDate: new Date(Date.now() - 86400 * 1000),
3  limit: 10
4})
5
6for (const correlation of correlations) {
7  console.log("Food intake at:", correlation.startDate)
8
9  for (const sample of correlation.quantitySamples) {
10    const value = sample.quantityValue(sample.quantityType.includes("Energy")
11      ? HealthUnit.kilocalorie()
12      : HealthUnit.gram())
13    console.log(`${sample.quantityType}: ${value}`)
14  }
15}

Accessing Correlation Samples

Each correlation contains the following sample arrays:

  • quantitySamples: All quantity samples (including cumulative/discrete)
  • cumulativeQuantitySamples: Only cumulative quantity samples
  • discreteQuantitySamples: Only discrete quantity samples
  • categorySamples: Any associated category samples (for future support)

You can use .quantityType and .quantityValue(unit) to interpret each sample.

Error Handling

1try {
2  const results = await Health.queryCorrelations("bloodPressure")
3  console.log("Found", results.length, "records")
4} catch (err) {
5  console.error("Failed to query correlations:", err)
6}

Summary

To read correlation data from HealthKit:

  1. Call Health.queryCorrelations(type, options)
  2. Iterate through each HealthCorrelation
  3. Access quantitySamples or categorySamples
  4. Use .quantityValue(unit) to extract values

This is useful for composite health records like blood pressure or nutrition intake.

Outline